Managing Python Virtual Environments with UV

PyData Northern Utah | ASC Innovation Lab

Marc Dotson and Kaden Buffaloe

Background

What is a Python environment?

A Python environment is composed of the Python version and library versions (including dependencies)

Why manage your Python environments?

It is not uncommon for different projects to require different Python versions and different library versions

Why manage your Python environments?

It is not uncommon for different projects to require different Python versions and different library versions

Welcome to “dependency hell”

What makes a Python environment virtual?

A Python virtual environment (a.k.a., a project environment) is a self-contained, project-specific environment

My code works on my machine, so what?

Project environments can be reproduced on another machine by you (including future you) or someone else

  1. Code
  2. Code, Python version, and library versions
  3. Code, Python version, library versions, and OS

My code works on my machine, so what?

Project environments can be reproduced on another machine by you (including future you) or someone else

  1. Code
  2. Code, Python version, and library versions
  3. Code, Python version, library versions, and OS

If you need to reproduce something about your machine beyond your code, Python version, and library versions, you’ll want to use a container

Why uv?

uv is an extremely fast Python package and project manager, written in Rust

  • A single tool to replace conda, pip, poetry, pyenv, virtualenv, etc.
  • Installable via the command line without Rust or Python
  • Supports macOS, Linux, and Windows
  • Easy to integrate with or transfer from existing tools

Walkthrough

Install uv

Get started by installing uv via the command line (i.e., the programming interface into your OS itself)

macOS and Linux via Terminal

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows via PowerShell

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Restart your command line and run uv to verify it has been installed

Install and manage Python versions

Once you have uv installed, it’s easy to install and manage Python different versions from the command line

  • Install the latest stable Python release with uv python install
  • Install a specific Python version, like uv python install 3.13.4
  • View Python versions you can install with uv python list
  • Find which Python versions you have installed with uv python find
  • Uninstall a specific Python version, like uv python uninstall 3.13.4

There’s lots more uv can do to manage Python versions

Create or navigate to a project directory

Using the command line or a code editor (i.e., VS Code, Cursor, Positron, etc.), create or navigate to a project directory, preferably one that is not being synced to the cloud via OneDrive, iCloud, etc.

macOS and Linux via Terminal

cd ~/Desktop
mkdir uv-practice
cd uv-practice

Windows via PowerShell

cd Desktop
mkdir uv-practice
cd uv-practice

Dragging a folder from your finder/file explorer and dropping it into the terminal/shell will paste its file path

Initialize a project environment

Run uv init to initialize a project environment in your project directory and create a pyproject.toml file, the Python standard for defining configurations for a project, along with

  • .gitignore is a hidden file for turning your project directory into a Git repository
  • .python-version is a hidden file that specifies the version of Python for the project
  • main.py is a Python script you can use or delete
  • README.md is a markdown file that is also used in Git repositories that you can use or delete
uv-practice
├── .gitignore
├── .python-version
├── main.py
├── pyproject.toml
└── README.md

Install libraries

With the project environment initialized, we can now install libraries, like uv add polars, which install the Polars library along with any dependecies, along with

  • uv.lock file that keeps track of the library versions you’ve installed
  • .venv a hidden folder that contains the libraries for the project environment
uv-practice
├── .venv
├── .gitignore
├── .python-version
├── main.py
├── pyproject.toml
├── README.md
└── uv.lock

Other details

That’s it! You now have a project environment managed by uv and can go ahead and use your favorite code editor to run Python code

  • Whenever you install new libraries using uv add <library>, the uv.lock file is automatically updated
  • If you’re starting with an existing project environment, uv run automatically installs any missing libraries from the uv.lock file
  • If you need to share your project enviornment in the form of a requirements.txt, run uv export --format requirements.txt
  • If you need to share your project enviornment in the form of a pylock.toml, run uv export -o pylock.toml

And there’s a lot more thatn uv can do